/**
 * Log
 *
 * @author Chris Pratt
 *
 * 10/23/2007
 */
package com.anodyzed.onyx.log;

import com.anodyzed.onyx.text.TextFormat;

/**
 * Java 5 Log Facade - Allows using format strings and variable argument lists
 * to build log messages efficiently.
 *
 * Since there is no up-front string processing used to construct the log
 * message, if the logger is set above the level of the log method called, it is
 * quickly and quietly ignored, with no processing.
 *
 * If, on the other hand, the log level is below the level of the log method
 * called, the format string is processed and the supplied arguments are used to
 * build the log message.
 *
 * The Log message format string is comprised of static text with interspersed
 * replacement argument placeholders.  The placeholders begin with '{' and end
 * with '}'.
 *
 * Example:
 *   <code>"Simple {0}, More Complex {1.lastname}, Even More Complex
 *   {2.address.city}, Most Complex {1.birthDate,date,yyyyMMdd}"</code>
 *
 * The simplest is just the (zero based) index of the argument used to replace
 * the placeholder.  Additionally you can add a dot separated string of bean
 * property names to access from the indexed argument. Lastly, you can use the
 * java.text.MessageFormat style comma separated format descriptors to format
 * each replacement element.
 *
 * Example:
 *   <code>log.debug("Simple {0}, More Complex {1.lastname}, Even More Complex
 *   {2.address.city}, Most Complex {1.birthDate,date,yyyyMMdd}",
 *   5, user, company);</code>
 *
 * Might write out:
 *   <code>Simple 5, More Complex Chris, Even More Complex Sacramento,
 *   Most Complex 19640123</code>
 *
 * Oh, one last thing, if the last argument is an instance of Throwable, it will
 * be passed on to Log4j's Throwable support 
 *  
 * @see com.anodyzed.onyx.text.TextFormat 
 */
public interface Log {

  /**
   * Test whether the logger is enabled for the supplied Logging Priority
   *
   * @param lvl The Log Priority Level
   * @return true if enabled
   */
  boolean isEnabledFor (LogLevel lvl);

  /**
   * Write a Log Message at the supplied Logging Priority
   *
   * @param lvl The Log Priority Level
   * @param fmt The Log message format string
   * @param args The replacement arguments
   */
  void log(LogLevel lvl,String fmt,Object... args);

  /**
   * Write a Log Message at the supplied Logging Priority using the pre-parsed 
   * <code>TextFormat</code> 
   *
   * @param lvl The Log Priority Level 
   * @param fmt The <code>TextFormat</code> for the message 
   * @param args The replacement arguments 
   */
  void log(LogLevel lvl,TextFormat fmt,Object... args);

  /**
   * Log all the Readable Properties in a Bean
   *
   * @param lvl The Log Priority Level
   * @param msg The lead in Message 
   * @param bean The Bean to Log 
   */
  void bean(LogLevel lvl,String msg,Object bean);

  /**
   * Check whether Trace Logging is Enabled
   *
   * @return true if trace logging is enabled
   */
  boolean isTraceEnabled();

  /**
   * Write out a trace level message
   *
   * @param fmt The Log Message Format String
   * @param args The replacement arguments
   */
  void trace(String fmt,Object... args);

  /**
   * Write out a trace level message formatted with the pre-parsed
   * <code>TextFormat</code> 
   *
   * @param fmt The <code>TextFormat</code> for the message
   * @param args The replacement parameters
   */
  void trace(TextFormat fmt,Object... args);

  /**
   * Write out the bean properties at the trace level
   *
   * @param msg A descriptive message
   * @param bean The Bean being debugged
   */
  void traceBean(String msg,Object bean);

  /**
   * Check whether Debug Logging is enabled
   *
   * @return true if debug logging is enabled
   */
  boolean isDebugEnabled();

  /**
   * Write out a debug level message
   *
   * @param fmt The Log message format string
   * @param args The replacement arguments
   */
  void debug(String fmt,Object... args);

  /**
   * Write out a debug level message formatted with the pre-parsed
   * <code>TextFormat</code> 
   *
   * @param fmt The <code>TextFormat</code> for the message
   * @param args The replacement parameters
   */
  void debug(TextFormat fmt,Object... args);

  /**
   * Write out the bean properties at the debug level
   *
   * @param msg A descriptive message
   * @param bean The Bean being debugged
   */
  void debugBean(String msg,Object bean);

  /**
   * Check whether informational logging is enabled
   *
   * @return true if enabled
   */
  boolean isInfoEnabled();

  /**
   * Write out an informational level message
   *
   * @param fmt The Log message format string
   * @param args The replacement arguments
   */
  void info(String fmt,Object... args);

  /**
   * Write out an informational level message formatted with the pre-parsed
   * <code>TextFormat</code> 
   *
   * @param fmt The <code>TextFormat</code> for the message
   * @param args The replacement parameters
   */
  void info(TextFormat fmt,Object... args);

  /**
   * Check whether warning logging is enabled
   *
   * @return true if enabled
   */
  boolean isWarnEnabled();

  /**
   * Write out a warning level message
   *
   * @param fmt The Log message format string
   * @param args The replacement arguments
   */
  void warn(String fmt,Object... args);

  /**
   * Write out a warning level message formatted with the pre-parsed
   * <code>TextFormat</code> 
   *
   * @param fmt The <code>TextFormat</code> for the message
   * @param args The replacement parameters
   */
  void warn(TextFormat fmt,Object... args);

  /**
   * Write out an error level message
   *
   * @param fmt The log message format string
   * @param args The replacement arguments
   */
  void error(String fmt,Object... args);

  /**
   * Write out an error level message formatted with the pre-parsed
   * <code>TextFormat</code> 
   *
   * @param fmt The <code>TextFormat</code> for the message
   * @param args The replacement parameters
   */
  void error(TextFormat fmt,Object... args);

  /**
   * Get the Effective Level for this Logger
   *
   * @return Logging Level
   */
  LogLevel getEffectiveLevel();

} //*Log
